upsf95 - X11 based Fortran 95 debugger
Upsf95 is the Fortran 90/95 debugger for use with the NAGWare f95 compiler. It is a debugger with a graphical user interface, and is a modified version of the open-source debugger ``ups''.
The program to be debugged should be compiled and linked with the -g option.
Upsf95 runs in its own window, thus not interfering with the user program's I/O. The upsf95 window has two major areas - one showing a structured document representing the state, the other showing the source that is being executed.
Upsf95 needs little documentation for normal use, as its interface is very straightforward. While stepping through the program, the next source line to be executed is shown highlighted in the source code window, and breakpoints are shown interspersed as pseudo-code.
Upsf95 contains the same support for debugging C code as the original ups debugger.
upsf95 executable-file [core-file|process-id] [-a user-args]
This section contains a simple example of the use of upsf95 on a small sample Fortran program.
MODULE fh4 REAL :: r = -HUGE(0.0) END MODULE fh4 PROGRAM fh4_prog USE fh4 COMMON/fh4com/i CALL sub(2) PRINT *,i,r END PROGRAM fh4_prog SUBROUTINE sub(j) USE fh4 COMMON/fh4com/i r = 0.5*j i = j*3 END SUBROUTINE sub
Assuming the above code is in the file ``sample.f90'', it may be debugged as follows:
Upsf95 will create a separate window for debugging, divided into two main subwindows and a number of boxes. The top region is the ``display area'', and contains captions like:
Target a.out a.out Signals Environment Untyped variables Source files Functions Breakpoints
The beginning of the main program will be displayed in the lower region.
All the objects in the display area (except ``Functions'') can be selected like this and have their own menus.
Function: activewith the cursor positioned immediately after ``Function:''.
#stop;will appear at the start of the main program in the source region.
Upsf95 represents breakpoints as this fragment of pseudo-code. You can also add breakpoints by right-clicking on the target line in the source region (see later).
To run the program, left-click on ``Start''. It will start and almost immediately hit the breakpoint you just set. You should see the first line of code in main highlighted. This means that execution has stopped just before this line. If you look at the display area you will also see that a new line has appeared under the ``Functions'' object. This should look like:
main sample.f90:5
This shows that you are stopped at line 5 of sample.f90 in function main.
At this point you are in the usual state for upsf95: you have the target stopped, with the line that is about to be executed highlighted in the source window and your current position in the source file shown under the ``Functions'' object in the display area.
The source display will highlight each line as you step through it (some lines take several steps to complete). Click on ``Step'' several times until you step into the subroutine sub; the source display now switches to subroutine sub, which you have just stepped into. You will also see an extra line under ``Functions'' - the display should look like:
main sample.f90:8 sub sample.f90:15
As you can see this is a stack trace, showing you which function called which starting from main and working down to the function you are currently stopped in.
You should see a line added to the stack trace, making it look like:
main sample.f90:8 sub sample.f90:15 Integer :: J 2
This is showing that j is a variable of type INTEGER with the value 2.
Any variable that is visible in the source window can thus have its type and value displayed by clicking on its name. (A variable that is not visible in the source window can be displayed by selecting (left-clicking on) the procedure in which it occurs in the ``Functions'' list, and using the ``Add expr'' button in the top menu.)
Now left-click on ``r'' at the beginning of the source line. You should see a line added above the stack trace, which looks like:
Real :: R -3.402823466E+38
Because r is a module variable, it is not part of any single procedure and so not stored on the stack.
The display for variable r is highlighted, and the value changes to half that of j, i.e.
Real :: R 1.000000000Displayed variables remain in the display area as you step through the program code so you can watch the values change.
The target continues to completion and exits. The value printed for r in the original window will be 37. The stack trace and variables disappear from the display area, and all the target control menu captions except for ``Start'' are greyed out to indicate that they are unavailable while the target is stopped.
Another way of setting breakpoints is to use the source display. Simply scroll the source display to the required source line and right-click.
If instead of right-clicking you press and hold the right mouse button you will see a popup menu with the captions ``Add breakpoint'', ``Execute to here'', ``Jump to here'', and ``Edit source''. You will also have seen an arrow to the left of the menu pointing at the source line you pressed the mouse over.
The default selection is ``Add breakpoint'', so a simple right-click will add a breakpoint immediately before the source line. When a breakpoint is added the text #stop; appears in the place where the breakpoint will occur.
This is the simplest and most common way of adding breakpoints in upsf95. The normal sequence of actions is:
All editable fields in upsf95 work in the same way. To start editing you click the middle mouse button over the editable text. A black ``marker bar'' appears - characters that you type appear to the left of this marker bar. You can reposition the marker bar by clicking in the new position with the middle mouse button, or by using one of the cursor movement key sequences described below.
Clicking the left or right button confirms the edit. Clicking the middle mouse button outside the editable text area also confirms the edit. In both cases the mouse click is then interpreted as normal - this means that to confirm an edit you can simply move on to another activity. The final way to confirm an edit is to type ESC (the escape key) or click the left mouse button on the Enter Button (the small region to the right of the typing line with the "<<" image).
To paste the current window system cut buffer, use Control-Y or click the middle mouse button on the Enter Button.
When you try to confirm an edit, upsf95 checks that the new field value is reasonable. If not you get an error message and you are left in the edit. An immediate second attempt to quit abandons the edit and restores the original field value.
When editing, upsf95 uses similar command keys to emacs. These key bindings are:
Control-A | Move to start of line |
Control-B, LEFT | Move backwards one character |
Control-C | Cancel edit (not an emacs binding) |
Control-D | Delete character forwards |
Control-E | Move to end of line |
Control-F, RIGHT | Move forward one character |
Control-K | Delete to end of line |
Control-N, DOWN | Move down a line, if possible, otherwise retrieve the next later item in the history buffer |
Control-P, UP | Move up a line, if possible, otherwise retrieve the next previous item in the history buffer |
Control-U | Delete to start of line (not an emacs binding) |
Control-W | Delete text between mark and point |
Control-Y | Paste X selection |
Alt-@, Alt-space | Set mark |
Alt-B | Move backwards one word |
Alt-D | Delete word forwards |
Alt-F | Move forward one word |
Alt-M | Move to first non-whitespace character |
Alt-Delete | Delete word backwards |
Delete | Delete character backwards |
Escape | Finish edit |
Return | In an editable field, finish the edit. In the source window, start a new line. |
Alt-> | Move to end of buffer |
Alt-< | Move to start of buffer |
If you run upsf95 from a terminal (or a terminal emulator like xterm), it tries to discover what keys you are using for delete and line erase. If this fails it takes both ^H (backspace) and DEL to mean delete, and ^U to mean line erase.
Most of the editable fields in upsf95 have their own history of recently typed commands. For example, there is a history of typing line commands, a history of breakpoint code entered, and a history of variable values changed.
Pressing the Left mouse button on the History Button, the small region to the right of the typing line with the triangular image, pops up a menu of recently entered data for that field.
When editing most single line fields, a Control-P, or up arrow moves the history pointer back one entry and replaces the current text with the previous entry. Typing a Control-N, or down arrow, moves the history pointer forward one entry.
Edit histories are saved between sessions of upsf95 in ups-state/editHistory, if you use the ups-state feature, or in the file ~/.upsEditHistory if not.
Text can be selected by holding the left mouse button down and moving the cursor. Selected text will be highlighted. Releasing the button sets the selection.
Selected text can be pasted into an edit with Control-Y or by clicking the middle mouse button on the Enter Button (the small region to the right of the typing line with the ``<<'' image).
Note that in the source window, left-clicking on a variable name (without dragging) adds the variable name to the stack frame display; only if the mouse is moved is the text made into a plain X selection (and not added to the stack frame display unless the Shift key was also being held down).
When the target gets a signal control returns to upsf95. Depending on the signal and the way you have specified it should be handled, the target is either stopped or restarted (possibly with a display refresh), and the signal can either be passed on to the target or ignored. Signal handling can be controlled using the ``Signals'' object in the display area.
Upsf95 recognises many common X11 command line arguments. These include:
The appearance of upsf95 is controlled by the use of X11 resources with the prefix ``upsf95'', or if that is not found, ``Ups''. The default appearance if no resource is found is taken from the file ``Ups'' in the NAGWare f95 compiler library directory. See the ups documentation for a full list of recognised X11 resources.
On the Apple Mac OS X only, where this document says ``left click'', this is a normal mouse click. Where it says ``middle click'', hold the Alt key down and click. Where it says ``right click'', hold the Apple key down and click.
f95(1), ups(1), http://ups.sourceforge.net/main.html.
Please report any bugs found to ``support@nag.co.uk'' or ``infodesk@nag.com'', along with any suggestions for improvements.